COMMENT ⊗   VALID 00005 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00002 00002		     Programming for the Ethernet device on WAITS
C00005 00003				     Raw packet mode
C00008 00004				       BSP mode
C00014 00005	This file was previously written by 1,MRC using E on 10-Feb-81 at 0037
C00021 ENDMK
C⊗;
	     Programming for the Ethernet device on WAITS

     The Ethernet on WAITS is implemented as a device driver for
device PUP:.  Most of the standard WAITS I/O UUOs apply to the PUP:
device.  The Ethernet may be used either in "BSP mode" (in which case
the system provides flow control) or in "raw packet mode".  This is
determined by the I/O data mode the PUP: channel is OPENed or INITed
in.  Dump mode indicates raw packet mode, which a buffered I/O mode
indicates BSP mode.  It is possible while an I/O channel is open to
switch modes via the SETSTS UUO, although I don't recommend it and
anybody who does it will probably be boiled in oil and forced to
program in PASCAL or FORTRAN or some such other horrendous language.

     The I/O UUO's described here may return any of the following
error bits in the I/O status word if they fail.

Name	Interpretation
----	--------------
IOIMPM	Connection not in proper state; the connection either never
	 was opened or is in the process of closing.
IODERR	The console PDP-11 did not accept the Pup (it is probably
	 sick and needs attention).  Only happens on a datagram OUTPUT.
IODTER	Time out; the Pup was not answered within a pre-determined
	 time out interval.  Probably the other host is dead or at
	 least the remote server is down.
IOBKTL	The other host sent us a Pup larger than we can handle in BSP
	 mode.  Since we never allocate it a Pup that large, it is
	 violating protocol.
IODEND	The connection has closed; no more Pups are available for input.
			     Raw packet mode

     Before sending any Pups in raw packet mode, a link must be
established.  A link is a system resource which specifies the local
socket, the remote socket, and the remote host.  A link is created
by using the LOOKUP UUO as follows:
	LOOKUP <channel>,<block>
	 <failed, local socket busy or no more links available>
	<success>
	...
block:	<local socket>
	<foreign socket>
	<foreign host>
The LOOKUP UUO is an illegal UUO if the I/O channel is not in dump
mode or if the arguments are invalid in any way.  A LOOKUP given
on an I/O channel which already has a link changes that link's
parameters.

     A link is destroyed by the UTPCLR UUO:
	UPTCLR <channel>,
Link destruction is also done by a RELEASE UUO, except that UTPCLR
does not release the I/O channel.

     A Pup is read with the INPUT UUO, as follows:
	INPUT <channel>,<block>
	...
block:	<Pup readin block, at least 140. words long>
The Pup readin block receives the entire Pup including the Ethernet
header.  The system already has validated the checksum.  If no Pups
are available to read INPUT will wait until one appears.

     A Pup is sent with the OUTPUT UUO, as follows:
	OUTPUT <channel>,<block>
	...
block:	<Pup output block, at most 140. words long>
The Pup output block is an image of the Pup to be sent.  The system
will fill in most of the Pup header, including the Ethernet message
type, the host/sockets, and the checksum; however the user may
specify the Pup type.  OUTPUT is an illegal UUO if the length of the
Pup is too large or too small.

     One Pup MTAPE is meaningful in raw Pup mode, the .MTSIP function.
See the next page for further details.
			       BSP mode

     BSP mode is a simple data stream mode, using the standard WAITS
I/O UUO's (IN/OUT/INPUT/OUTPUT).  From time to time on input, there
will be padding nulls at the end of a word.  These are indicated by
the low order two bits of the word being non-zero; these bits contain
the number of significant data bytes in the word (note that a zero
count means that the entire word is significant).  Many user programs
will ignore nulls and need not worry about checking this count.

     For buffers sent without filling up a packet's worth of data,
the output code checks the byte count in the user's buffer header.
Therefore the buffer header byte count must accurately reflect the
number of free bytes in the buffer.  For most programs this is no
hardship unless the programmer tries to be cute.

     A CLOSE UUO (either executed directly or implicitly by a RELEASE)
closes the BSP connection.

     Non-I/O portions of the connection are accomplished by the MTAPE
UUO.  An MTAPE call is of the form
	MTAPE <channel>,<block>
	 <error return>
	<success return>
	...
block:	<function code>
	<status word>
	<possible function arguments>


     The words of a PUP MTAPE block is:
Name	Offset	Interpretation
-----	-----	--------------
MT%FCN	0	Function code.
MT%STA	1	Status word, set by all functions.
MT%MRK	2	Mark value (read by .MTSMR, set by .MTRMR).
MT%SKT	2	Socket number (read by .MTCON and .MTLSN), note that
		 this is the same offset as MT%MRK, but no function
		 uses both.
MT%HST	3	Host address (read by .MTCON, set by .MTLSN).

     The function code is one of the following:
Name	Value	Interpretation
-----	-----	--------------
.MTCON	0	Connect; this function establishes a connection to
		 the remote host with arguments in MT%SKT and MT%HST.
.MTLSN	1	Listen; wait for a connection request from a host on
		 the socket in MT%SKT, establish a connection, return
		 the remote host address in MT%HST.
.MTSMR	2	Send Mark; send a AMark Pup to the remote host with
		 Mark type in MT%MRK.
.MTRMR	3	Read Mark; return the type of the last read Mark in
		 MT%MRK.
.MTSIP	4	Skip if Input Present; return success if there is at
		 least one Pup on the input list (ie, an INPUT UUO
		 will not wait for a packet).
.MTSIN	5	Send Interrupt; send an Interrupt Pup.

     The status word presently is zero on a successful MTAPE, or
contains the error code on a failing MTAPE.  The error codes are:

Name	Value	Interpretation
-----	-----	--------------
%MTNIM	1	Not implemented.
%MTCIU	2	Channel in use; the channel is already associated
		 with a link, so an .MTCON or .MTLSN MTAPE is illegal.
%MTNLA	3	No links available; the system's table of Ethernet
		 links is full, therefore a new link cannot be
		 created by an .MTCON or .MTLSN MTAPE.
%MTNIA	4	No input available; this is the non-skip status
		 returned by an .MTSIP MTAPE.
%MTISK	5	Invalid socket; the socket for an .MTCON or .MTLSN
		 MTAPE is less than 1 or greater than $PUPMS
		 (currently 1000), the system maximum Pup server
		 socket.
%MTSIU	6	Socket in use; an .MTLSN MTAPE was done when a link
		 already exists.
%MTNLK	7	No link; the function requires a link to be associated
		 with the I/O channel, but none has been set up.
%MTTMO	10	Time out; the request didn't get the appropriate reply
		 from the host within a "reasonable" time, or a .MTLSN
		 took longer than 30 seconds.
This file was previously written by 1,MRC using E on 10-Feb-81 at 0037

...before I put my two cents in here, on 17-Apr-83  (AAM)
(most of the information here was gleaned by looking at the sources of
PUPSER and ETHFTP (also called PUPFTP).
  The source for PUPSER is in PUPSER[S,SYS]
  The source for ETHFTP is in ETHFTP.FAI[NET,TVR]

Device PUP can be opened in 3 different modes.  The mode is determined
from the data mode (this is the first word in the OPEN block).  The 3
PUP modes and corresponding data modes are:
   PACKET mode (data mode = 15 [SCOPE DUMP MODE])
   EFTP mode (data mode = 16 [DUMP RECORD MODE] or 13 [IMAGE BINARY MODE])
   BSP mode (data mode = anything else -- you should use 0 [ASCII MODE])

The MTAPE function is used to do certain functions on the PUP device.
The format is
	MTAPE	chan,block
	  <return>
	(there is only one return, and the success of the operation can
	 be determined by looking at the STATUS word in the block--see below)

The offsets in "block" are:
0	Opcode.  Selects what function to do. (see table below)
1	Status word.  Set as a result of certain conditions. 0 means no error.
2	Local socket.  -1 means let WAITS generate one.
3	Wait flag. -1 = wait for function to complete before continuing.
  NOTE there is a bug in PUPSER because the wait flag isn't handled consistently
4	Byte size.  Checked, but not used.
5	Foreign socket.  Again, -1 means generate one.
6	Foriegn host number.  -1 means this is a broadcast packet.

The opcodes are: (the notations	are BSP = BSP mode only, illegal = not allowed,
PKT = packet mode only) note that these opcodes are picked to be similar to the
IMP MTAPE opcodes...
	 0 ESTABLISH CONNECTION
	 1 LISTEN ON A SOCKET
	 2 GET STATUS BITS
	 3 TERMINATE CONNECTION (LIKE CLOSE UUO)
 BSP     4 WAIT FOR CONNECTION
	 5 GET POINTERS TO SYSTEM SYMBOLS
	 6 WAKE UP USER PROCESS FROM I-LEVEL
	 7 GET STATUS BLOCK (USED AFTER LISTEN)
	 10 SKIP IF IMP INPUT
 BSP     11 SEND INR/INS
 illegal 12 TURN ON NCP
 illegal 13 TURN OFF NCP
 BSP     14 TEST AND CLEAR INTERRUPT STATUS
	 15 SET ALLOCATION
	 16 GET ALLOCATION (IN IMPSER)
	 17 SET TIMEOUTS (IN IMPSER)
	 20 GET TIMEOUTS (IN IMPSER)
	 21 GENSYM A SOCKET FOR ICP
 illegal 22 SEND A RESET
 illegal 23 SEND HOST DOWN STATUS MESSAGE
 illegal 24 ATTEMPT TO UNWEDGE AN IMP CONNECTION
 BSP	 25 SEND A MARK
 BSP	 26 RECIEVE A MARK (OR EFTP ABORT CODE)
	 27 GET ROUTING TABLE
 PKT	 30 SET ROUTING TABLE

Some useful socket numbers:
 4 = socket for "miscellaneous services"

Some useful pup types:
 220 = name lookup
 221 = name lookup response
 222 = name lookup error response

Some useful sequences of operations:
-----------------------------------
To request a name -> host number from a name server, use PACKET mode, and
do a "listen" type MTAPE (opcode=1) with the receiving host = -1 (broadcast)
and the receiving socket = 4 (misc. server).
[If you set the wait flag = 0 the UUO will wait to return until the connection
is actually made; this is probably what you want to do.]
Next, send out a PUP on the same channel with the text of the name you want to
look up in the body of the pup and the pup type = 220.  Then use the "skip if
ready" MTAPE (opcode=10) to wait for the answering pup.  If the pup type of
the reply is 221 then the pup body will have all the host/socket numbers
matching in groups of 6 bytes, otherwise the pup body will have the text of
an error message.

I/O:
---
The IN and OUT UUOs can be used pretty much like any other device to do
I/O in BSP mode.  However, there is one extra hack to allow programs to
determine the number of bytes in the buffer on input.  The last four bits
in the last word in the buffer correspond to the last four bytes in that
word; any bit that is "1" is indicating that its corresponding byte is
not part of the data.  I.e., if there is only one data byte in the last
word, the low-order 4 bits will be 7; if there are two data bytes, the
low-order 4 bits will be 3, etc.  The OUT UUO will also look at these
bits if you set them up.  Note that ignoring these bits will work if you
don't mind having extra nulls at the end of the data (on both input and
output).

Status word bits: (from GETSTS)
40000 = a mark was seen, in BSP mode.  The MTAPE UUO has to be used to
	read the mark.
20000 = EOF.  This happens when the other end closes the connection.